Skip to content

feat(sync): live upload with transcribeLive() and openLive() - #177

Merged
ccampbell-aai merged 3 commits into
mainfrom
ccampbell/node-sync-live
Sep 10, 2026
Merged

ccampbell-aai merged 3 commits into
mainfrom
ccampbell/node-sync-live

Conversation

@ccampbell-aai

@ccampbell-aai ccampbell-aai commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Adds live upload to the Sync API: audio is uploaded while it is still being recorded, so every speech segment but the last is transcribed before the speaker stops. On a paced 7-second clip the wait after the last byte is roughly half that of the buffered transcribe(), with a byte-identical transcript.

API

// Push style, for callback sources (microphone, WebRTC, telephony):
const session = client.sync.openLive({ sample_rate: 16_000, channels: 1 });
mic.on("data", (chunk) => session.write(chunk));
mic.on("end", () => session.close());
const { text } = await session.result();

// Pull style, for a source that is already a stream:
const result = await client.sync.transcribeLive(recorder.stdout, { sample_rate: 16_000, channels: 1 });
  • client.sync.transcribeLive(audio, config?, options?) — audio is an async iterable (Node streams included), a sync iterable, or a web ReadableStream<Uint8Array>. Same config and result type as transcribe(). Bytes, a Blob, or a path are rejected by name, pointing at transcribe().
  • client.sync.openLive(config?, options?) → SyncLiveSession — for sources that deliver audio through a callback. write(chunk) queues audio (never blocks), close() ends it, result() resolves with the transcript, abort() drops the request, closed reports state, and stream() returns a WritableStream so a web stream can be piped in. The request starts the moment the session opens.
  • Exported from the package root: SyncLiveSession, and the SyncLiveAudioInput / SyncLiveOptions types.

It posts multipart/form-data to POST /v1/transcribe/live, streamed with Transfer-Encoding: chunked so the request can start before the audio exists. The config part is sent first and is always present ({} when empty), which the endpoint requires.

Behavior

  • options.timeout (default 180 s) is a whole-request deadline covering the recording as well as the transcription, and options.signal cancels the request. The Sync API still caps audio at 120 s.
  • Authorization, rate-limit, and capacity failures surface as a SyncTranscriptError, and can arrive part-way through the upload rather than only at the end.
  • session.write() after the session has ended drops the chunk rather than throwing, so a capture callback that outlives teardown cannot crash the process. A non-bytes chunk still raises a TypeError at the call site.

Tests

27 unit tests in tests/unit/sync-live.test.ts cover the body framing, config-first ordering, PCM, filename escaping, input rejections, mid-upload errors, and the full session lifecycle including abort and post-end writes. The full unit suite passes on Node 18 and 20 and across the httpx-free matrix; tsc, ESLint, Prettier, and publint are clean. A new samples/sync-live-from-mic records from the microphone and transcribes through openLive().

🤖 Generated with Claude Code

@ccampbell-aai
ccampbell-aai force-pushed the ccampbell/node-sync-live branch from 71d0cde to 3cf564d Compare September 10, 2026 17:12
ccampbell-aai and others added 2 commits September 10, 2026 11:12
Port the Sync API live upload from the Python SDK. Both post to
POST /v1/transcribe/stream with a hand-framed multipart body streamed as
a chunked ReadableStream (duplex: "half"), config part first and always
present, so the request starts before the audio exists and every speech
segment but the last is transcribed while the caller is still recording.

- client.sync.transcribeLive(audio, config?, options?) — pull-style, for
  sources that already are async iterables (Node streams included), sync
  iterables, or web ReadableStreams. Bytes, a Blob or a path are rejected
  by name, pointing at transcribe().
- client.sync.openLive(config?, options?) => SyncLiveSession — push-style,
  for callback-driven sources. write()/close()/result()/abort()/closed and
  a stream() WritableStream adapter. Exported from the package root with the
  SyncLiveAudioInput and SyncLiveOptions types.

Node-specific handling, verified live against undici on Node 26:
- The fetch timeout is a whole-request deadline (not per-operation as in
  httpx), so the live default is 180 s and must cover the recording; a
  hand-rolled deadlineSignal merges it with an optional caller signal
  without AbortSignal.any (Node 20+).
- A producer error surfaces from fetch as an opaque "fetch failed"; the
  original is captured and rethrown unwrapped.
- The server can reject mid-upload: fetch resolves with the status at once
  but withholds the body until the request body ends, so on a non-200 the
  SDK finishes the body itself rather than stream the rest of a rejected
  recording, and the error surfaces in ~150 ms instead of at the timeout.
- session.write() after the session ends drops the chunk rather than
  throwing, so a capture callback outliving teardown cannot crash the
  process. This is the one deliberate divergence from the Python session.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- README: two collapsible blocks under the sync section — openLive() with a
  SoX microphone example, and transcribeLive() showing the on-disk-file
  anti-pattern versus a recorder stream, plus the shared caveats (overlap-only
  win, 120 s cap, silence abort, mid-upload errors, raw PCM fields).
- CLAUDE.md: transcribeLive/openLive API bullets, a Live upload section, and a
  gotcha on the total-deadline timeout versus the 120 s audio cap.
- New samples/sync-live-from-mic (SoX helper shared with the streaming sample).
- CHANGELOG 4.39.0; version 4.38.0 -> 4.39.0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ccampbell-aai
ccampbell-aai force-pushed the ccampbell/node-sync-live branch from 3cf564d to 11d1cd2 Compare September 10, 2026 17:12
Comment thread src/services/sync/live.ts Resolved
@ccampbell-aai
ccampbell-aai marked this pull request as ready for review September 10, 2026 22:07
abort() guarded only on isAborted, so calling it after the request had
already settled flipped isAborted and made a later result() throw the
aborted error instead of returning the finished transcript. Guard on
isSettled too, matching the documented "no-op once the request has
completed" contract.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ccampbell-aai
ccampbell-aai merged commit fb06b96 into main Sep 10, 2026
3 checks passed
@ccampbell-aai
ccampbell-aai deleted the ccampbell/node-sync-live branch September 10, 2026 23:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants